<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.7"/>
<title>FlatBuffers: Use in Java/C-sharp</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="style.css" rel="stylesheet" type="text/css" />
<link href="https://fonts.googleapis.com/css?family=Roboto:300,400,400italic,500,500italic,700,700italic|Roboto+Mono:400,700" rel="stylesheet">
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea" style="height: 110px;">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="commonprojectlogo">
    <img alt="Logo" src="fpl_logo_small.png"/>
  </td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">FlatBuffers
   </div>
   <div style="font-size:12px;">
    An open source project by <a href="https://developers.google.com/games/#Tools">FPL</a>.
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.7 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md__java_usage.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Use in Java/C-sharp </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. Generate code for Java with the <code>-j</code> option to <code>flatc</code>, or for C# with <code>-n</code> (think .Net).</p>
<p>Note that this document is from the perspective of Java. Code for both languages is generated in the same way, with only minor differences. These differences are <a href="#differences-in-c-sharp">explained in a section below</a>.</p>
<p>See <code>javaTest.java</code> for an example. Essentially, you read a FlatBuffer binary file into a <code>byte[]</code>, which you then turn into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p>
<div class="fragment"><div class="line">ByteBuffer bb = ByteBuffer.wrap(data);</div>
<div class="line">Monster monster = Monster.getRootAsMonster(bb);</div>
</div><!-- fragment --><p>Now you can access values much like C++:</p>
<div class="fragment"><div class="line"><span class="keywordtype">short</span> hp = monster.hp();</div>
<div class="line">Vec3 pos = monster.pos();</div>
</div><!-- fragment --><p>Note that whenever you access a new object like in the <code>pos</code> example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), there's a second <code>pos()</code> method to which you can pass a <code>Vec3</code> object you've already created. This allows you to reuse it across many calls and reduce the amount of object allocation (and thus garbage collection) your program does.</p>
<p>Java does not support unsigned scalars. This means that any unsigned types you use in your schema will actually be represented as a signed value. This means all bits are still present, but may represent a negative value when used. For example, to read a <code>byte b</code> as an unsigned number, you can do: <code>(short)(b &amp; 0xFF)</code></p>
<p>The default string accessor (e.g. <code>monster.name()</code>) currently always create a new Java <code>String</code> when accessed, since FlatBuffer's UTF-8 strings can't be used in-place by <code>String</code>. Alternatively, use <code>monster.nameAsByteBuffer()</code> which returns a <code>ByteBuffer</code> referring to the UTF-8 data in the original <code>ByteBuffer</code>, which is much more efficient. The <code>ByteBuffer</code>'s <code>position</code> points to the first character, and its <code>limit</code> to just after the last.</p>
<p>Vector access is also a bit different from C++: you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by <code>Length</code> let's you know the number of elements you can access:</p>
<div class="fragment"><div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i &lt; monster.inventoryLength(); i++)</div>
<div class="line">    monster.inventory(i); <span class="comment">// do something here</span></div>
</div><!-- fragment --><p>Alternatively, much like strings, you can use <code>monster.inventoryAsByteBuffer()</code> to get a <code>ByteBuffer</code> referring to the whole vector. Use <code>ByteBuffer</code> methods like <code>asFloatBuffer</code> to get specific views if needed.</p>
<p>If you specified a file_indentifier in the schema, you can query if the buffer is of the desired type before accessing it using:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span> (Monster.MonsterBufferHasIdentifier(bb)) ...</div>
</div><!-- fragment --><h2>Buffer construction in Java</h2>
<p>You can also construct these buffers in Java using the static methods found in the generated code, and the FlatBufferBuilder class:</p>
<div class="fragment"><div class="line">FlatBufferBuilder fbb = <span class="keyword">new</span> FlatBufferBuilder();</div>
</div><!-- fragment --><p>Create strings:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> str = fbb.createString(<span class="stringliteral">&quot;MyMonster&quot;</span>);</div>
</div><!-- fragment --><p>Create a table with a struct contained therein:</p>
<div class="fragment"><div class="line">Monster.startMonster(fbb);</div>
<div class="line">Monster.addPos(fbb, Vec3.createVec3(fbb, 1.0f, 2.0f, 3.0f, 3.0, (byte)4, (<span class="keywordtype">short</span>)5, (byte)6));</div>
<div class="line">Monster.addHp(fbb, (short)80);</div>
<div class="line">Monster.addName(fbb, str);</div>
<div class="line">Monster.addInventory(fbb, inv);</div>
<div class="line">Monster.addTest_type(fbb, (byte)1);</div>
<div class="line">Monster.addTest(fbb, mon2);</div>
<div class="line">Monster.addTest4(fbb, test4s);</div>
<div class="line"><span class="keywordtype">int</span> mon = Monster.endMonster(fbb);</div>
</div><!-- fragment --><p>For some simpler types, you can use a convenient <code>create</code> function call that allows you to construct tables in one function call. This example definition however contains an inline struct field, so we have to create the table manually. This is to create the buffer without using temporary object allocation.</p>
<p>It's important to understand that fields that are structs are inline (like <code>Vec3</code> above), and MUST thus be created between the start and end calls of a table. Everything else (other tables, strings, vectors) MUST be created before the start of the table they are referenced in.</p>
<p>Structs do have convenient methods that even have arguments for nested structs.</p>
<p>As you can see, references to other objects (e.g. the string above) are simple ints, and thus do not have the type-safety of the Offset type in C++. Extra care must thus be taken that you set the right offset on the right field.</p>
<p>Vectors can be created from the corresponding Java array like so:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> inv = Monster.createInventoryVector(fbb, <span class="keyword">new</span> byte[] { 0, 1, 2, 3, 4 });</div>
</div><!-- fragment --><p>This works for arrays of scalars and (int) offsets to strings/tables, but not structs. If you want to write structs, or what you want to write does not sit in an array, you can also use the start/end pattern:</p>
<div class="fragment"><div class="line">Monster.startInventoryVector(fbb, 5);</div>
<div class="line"><span class="keywordflow">for</span> (byte i = 4; i &gt;=0; i--) fbb.addByte(i);</div>
<div class="line"><span class="keywordtype">int</span> inv = fbb.endVector();</div>
</div><!-- fragment --><p>You can use the generated method <code>startInventoryVector</code> to conveniently call <code>startVector</code> with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since the buffer is being constructed back to front. You then pass <code>inv</code> to the corresponding <code>Add</code> call when you construct the table containing it afterwards.</p>
<p>There are <code>add</code> functions for all the scalar types. You use <code>addOffset</code> for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate <code>create</code> function in-line, as shown above in the <code>Monster</code> example.</p>
<p>To finish the buffer, call:</p>
<div class="fragment"><div class="line">Monster.finishMonsterBuffer(fbb, mon);</div>
</div><!-- fragment --><p>The buffer is now ready to be transmitted. It is contained in the <code>ByteBuffer</code> which you can obtain from <code>fbb.dataBuffer()</code>. Importantly, the valid data does not start from offset 0 in this buffer, but from <code>fbb.dataBuffer().position()</code> (this is because the data was built backwards in memory). It ends at <code>fbb.capacity()</code>.</p>
<h2>Differences in C-sharp</h2>
<p>C# code works almost identically to Java, with only a few minor differences. You can see an example of C# code in <code>tests/FlatBuffers.Test/FlatBuffersExampleTests.cs</code>.</p>
<p>First of all, naming follows standard C# style with <code>PascalCasing</code> identifiers, e.g. <code>GetRootAsMyRootType</code>. Also, values (except vectors and unions) are available as properties instead of parameterless accessor methods as in Java. The performance-enhancing methods to which you can pass an already created object are prefixed with <code>Get</code>, e.g.:</p>
<div class="fragment"><div class="line"><span class="comment">// property</span></div>
<div class="line">var pos = monster.Pos;</div>
<div class="line"><span class="comment">// method filling a preconstructed object</span></div>
<div class="line">var preconstructedPos = <span class="keyword">new</span> Vec3();</div>
<div class="line">monster.GetPos(preconstructedPos);</div>
</div><!-- fragment --><h2>Text parsing</h2>
<p>There currently is no support for parsing text (Schema's and JSON) directly from Java or C#, though you could use the C++ parser through native call interfaces available to each language. Please see the C++ documentation for more on text parsing.</p>
<h3>Mutating FlatBuffers</h3>
<p>As you saw above, typically once you have created a FlatBuffer, it is read-only from that moment on. There are however cases where you have just received a FlatBuffer, and you'd like to modify something about it before sending it on to another recipient. With the above functionality, you'd have to generate an entirely new FlatBuffer, while tracking what you modify in your own data structures. This is inconvenient.</p>
<p>For this reason FlatBuffers can also be mutated in-place. While this is great for making small fixes to an existing buffer, you generally want to create buffers from scratch whenever possible, since it is much more efficient and the API is much more general purpose.</p>
<p>To get non-const accessors, invoke <code>flatc</code> with <code>--gen-mutable</code>.</p>
<p>You now can:</p>
<div class="fragment"><div class="line">Monster monster = Monster.getRootAsMonster(bb);</div>
<div class="line">monster.mutateHp(10);            <span class="comment">// Set table field.</span></div>
<div class="line">monster.pos().mutateZ(4);        <span class="comment">// Set struct field.</span></div>
<div class="line">monster.mutateInventory(0, 1);   <span class="comment">// Set vector element.</span></div>
</div><!-- fragment --><p>We use the somewhat verbose term <code>mutate</code> instead of <code>set</code> to indicate that this is a special use case, not to be confused with the default way of constructing FlatBuffer data.</p>
<p>After the above mutations, you can send on the FlatBuffer to a new recipient without any further work!</p>
<p>Note that any <code>mutate</code> functions on tables return a boolean, which is false if the field we're trying to set isn't present in the buffer. Fields are not present if they weren't set, or even if they happen to be equal to the default value. For example, in the creation code above we set the <code>mana</code> field to <code>150</code>, which is the default value, so it was never stored in the buffer. Trying to call mutateMana() on such data will return false, and the value won't actually be modified!</p>
<p>One way to solve this is to call <code>forceDefaults()</code> on a <code>FlatBufferBuilder</code> to force all fields you set to actually be written. This of course increases the size of the buffer somewhat, but this may be acceptable for a mutable buffer. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- Google Analytics -->
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-49880327-7', 'auto');
  ga('send', 'pageview');
</script>
</body>
</html>
